Authentication by API key
Important: This mode of authentication is intended for when the Web API is used for automation purposes. An API key is generated only for one user account. The recommended practice is to create a dedicated user account (and API key) for each automation 'service', and to ensure that the account has the minimum required permissions for the tasks involved. API keys should be controlled within your organisation in line with organisational IT policies. PlanningSpace does not store any API keys, however tenant administrators can disable the API access of single user accounts, or disable API access for all users.
For version 16.5 Update 13 and later: Authentication methods can be enabled or disabled for each tenant independently in IPS Manager (the default is all that all methods are enabled).
The disabling affects all interactive and API access for all user accounts of the specified type ('Local', 'SAML2', or 'Windows Active Directory'), and it includes API Key access.
If 'Local' accounts are disabled this will also disable the default 'Administrator' account for tenant administration.
Create a dedicated PlanningSpace user account
It is recommended to create a dedicated user account for each automation 'service'. Then it will be possible to set the user account permissions (i.e., workgroup memberships, hierarchy permissions, and permissions for individual data objects) to precisely match the requirements for the automation service.
The permissions used should always be the minimum required permissions.
Note: The user account must be granted the role 'Security/API Key' to generate an API key and to get access to the Web API endpoints. (The tenant Administrator will need to create a workgroup to manage access to the role.)
For managing user accounts, see PlanningSpace 16.5 User Manual: Users.
Generate an API key
Use a web browser to login to the PlanningSpace tenant web interface ('https://ips.mycompany.com/tenantname') using the credentials of the required user account. Only the specific user can generate an API key for that user account; the tenant Administrator cannot generate an API key, or see the value of the key (the value is not stored in PlanningSpace).
Navigate to the web page 'https://ips.mycompany.com/tenantname/PlanningSpace/#/generateApiKey'; click Create key and then copy the API Key that is generated. The API key is not recoverable after this point, even by the tenant Administrator.
The API key is an alphanumeric string which looks like the following example:
API.D49F43E5C0E64E2481FE15CBFDF9BE72.4744D25EB5A13EAE1B31B39D82EF7781
(See PlanningSpace 16.5 User Manual: Generate API Key.)
API key expiry (optional IPS service configuration)
For version 16.5 Update 7 and later: An API key can be set to expire a specific number of days after it is generated, based on the IPS setting 'API Key Lifetime'; this setting can only be changed by an IPS Administrator. The same setting applies across all tenants. The default setting is that expiry is disabled and API keys will have unlimited validity (i.e., the same as earlier versions of PlanningSpace). Changing the setting affects only newly-generated API keys; existing keys will maintain their original expiry date, or unlimited status.
The expiry date of the API key will be shown when it is generated. Also, you can check the expiration date of your existing API key by re-visiting the 'Generate API Key' web page.
The expiration date can also be found using the API GET request '/PlanningSpace/api/v1/users/apikeyexpiration', which requires that the requesting user has permission via the role 'Security/API Key' (otherwise the response will be 403); the return value contains the properties 'hasKey' (Boolean) and 'expirationDate' (string); if 'hasKey' is false (the user account has not got an API key) then 'expirationDate' will have value null, or if 'hasKey' is true then 'expirationDate' will either have the value null (meaning that the API key is unlimited and does not expire) or it will have a value which is the expiration date-time (e.g., '2021-01-12T18:07:57.947Z').
The stored key information for a user account does not change after the expiry date, therefore to determine if a user account has an active API key always requires a comparison of 'expirationDate' with the current date-time.
API key management
You can replace an API key at any time, by re-visiting the 'Generate API key' web page. If you lose the API key, then simply generate a new one.
The tenant Administrator can delete a user's API key using the User management interface. The user account can be blocked from using API keys by removing the account from the workgroup which is allowed the role 'Security/API Key'. All user access can be blocked by disabling the workgroups(s) that are allowed the role. (In either case, existing API keys will remain valid for when access to the role is re-enabled.)
API keys should be controlled within your organisation in accordance with organisational IT policies. PlanningSpace does not store any API keys.
Using an API key in HTTP Basic authentication
To use an API key in an API request, add an 'Authorization: Basic' header. This is typically used to handle 'username' and 'password' credential pairs. In this case, the API key is inserted as the password, and the username is the string 'FeedKey' or 'Account Key' (these are the default values for the IPS server setting 'AllowedApiKeyNames', which can be changed by the IPS Administrator).
The string 'FeedKey:APIKEY' (where 'APIKEY' is replaced by the actual API key string) must be Base64 encoded, and then inserted into the API request header. The code sample below illustrates this.
Code sample (PowerShell)
It is simple to use Windows PowerShell to do ad hoc API requests or to write scripts. The 'Invoke-RestMethod' command is available in all versions of PowerShell.
In the following, you will need to replace the string 'APIKEY' with an actual API Key for your PlanningSpace tenant. This creates a Base64 encoded string:
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(("{0}:{1}" -f 'FeedKey', 'APIKEY'))) You only need to do this once until the PowerShell is re-started.
Also, for convenience, set '$tenantUrl' to be the URL of your PlanningSpace tenant:
$tenantUrl = 'https://ipsserver.mycompany.com/TENANTNAME'Then, send each API request as in the following example, with an 'Authorization' header:
Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/api/v1/hierarchy/Tags?type=revision') -Headers @{'Authorization' = "Basic $base64AuthInfo"} Note that although the API response will originally be sent in the API response in JSON format, the Invoke-RestMethod command converts the response to a PowerShell object, which can be then be manipulated using native PowerShell operations. Alternatively, you can work with the JSON-format response by appending a pipe to the end of the command:
Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/api/v1/hierarchy/Tags?type=revision') -Headers @{'Authorization' = "Basic $base64AuthInfo"} | ConvertTo-JSON